package com.bank.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.bank.dto.Result;
import com.bank.entity.UserInfo;

import java.time.LocalDateTime;
import java.util.List;

/**
 * 客户信息服务接口
 * 提供客户信息相关的业务逻辑处理
 * 
 * @author 开发团队
 * @version 1.0.0
 * @since 2025-06-19
 */
public interface UserInfoService {

    /**
     * 新增客户信息
     * 
     * @param userInfo 客户信息
     * @return 操作结果
     */
    Result<UserInfo> addCustomer(UserInfo userInfo);

    /**
     * 根据客户ID删除客户信息
     * 
     * @param customerId 客户ID
     * @return 操作结果
     */
    Result<String> deleteCustomer(Integer customerId);

    /**
     * 批量删除客户信息
     * 
     * @param customerIds 客户ID列表
     * @return 操作结果
     */
    Result<String> batchDeleteCustomers(List<Integer> customerIds);

    /**
     * 修改客户信息
     * 
     * @param userInfo 客户信息
     * @return 操作结果
     */
    Result<UserInfo> updateCustomer(UserInfo userInfo);

    /**
     * 根据客户ID查询客户信息
     * 
     * @param customerId 客户ID
     * @return 客户信息
     */
    Result<UserInfo> getCustomerById(Integer customerId);

    /**
     * 根据身份证号查询客户信息（精确查询）
     * 
     * @param pid 身份证号
     * @return 客户信息
     */
    Result<UserInfo> getCustomerByPid(String pid);

    /**
     * 根据客户姓名模糊查询客户信息
     * 
     * @param customerName 客户姓名
     * @return 客户信息列表
     */
    Result<List<UserInfo>> getCustomersByNameLike(String customerName);

    /**
     * 根据联系电话模糊查询客户信息
     * 
     * @param telephone 联系电话
     * @return 客户信息列表
     */
    Result<List<UserInfo>> getCustomersByTelephoneLike(String telephone);

    /**
     * 根据创建时间范围查询客户信息（范围查询）
     * 
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 客户信息列表
     */
    Result<List<UserInfo>> getCustomersByCreateTimeRange(LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 分页查询客户信息（支持多条件组合查询）
     * 
     * @param page 分页参数
     * @param customerName 客户姓名（可选，支持模糊查询）
     * @param pid 身份证号（可选，精确查询）
     * @param telephone 联系电话（可选，模糊查询）
     * @param startTime 创建开始时间（可选）
     * @param endTime 创建结束时间（可选）
     * @return 分页结果
     */
    Result<IPage<UserInfo>> getCustomersPage(Page<UserInfo> page, String customerName, String pid, 
                                           String telephone, LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 获取所有客户信息
     * 
     * @return 客户信息列表
     */
    Result<List<UserInfo>> getAllCustomers();

    /**
     * 检查身份证号是否已存在
     * 
     * @param pid 身份证号
     * @param excludeCustomerId 排除的客户ID（用于修改时验证）
     * @return 是否存在
     */
    Result<Boolean> checkPidExists(String pid, Integer excludeCustomerId);

    /**
     * 检查联系电话是否已存在
     * 
     * @param telephone 联系电话
     * @param excludeCustomerId 排除的客户ID（用于修改时验证）
     * @return 是否存在
     */
    Result<Boolean> checkTelephoneExists(String telephone, Integer excludeCustomerId);

    /**
     * 获取客户统计信息
     * 
     * @return 客户总数
     */
    Result<Integer> getCustomerCount();

    /**
     * 导出客户信息到CSV文件
     * 
     * @return CSV文件内容
     */
    Result<String> exportCustomersToCSV();

    /**
     * 验证客户信息的完整性和合法性
     * 
     * @param userInfo 客户信息
     * @return 验证结果
     */
    Result<Void> validateCustomerInfo(UserInfo userInfo);
}
